Filtre de périphérique WebHID Frontend : Explication de la sélection de Périphériques d'Interface Humaine

L'API WebHID ouvre un monde de possibilités pour les applications web, leur permettant d'interagir directement avec des Périphériques d'Interface Humaine (HID) comme des manettes de jeu, des dispositifs d'entrée spécialisés, et plus encore. Une partie essentielle de l'utilisation efficace de WebHID est la compréhension des filtres de périphériques. Ce guide complet vous expliquera en détail les filtres de périphériques WebHID, vous donnant les moyens de créer des expériences web puissantes et engageantes.

Qu'est-ce que WebHID ?

WebHID est une API web qui permet aux applications web de communiquer avec des périphériques HID connectés à l'ordinateur ou à l'appareil mobile d'un utilisateur. Contrairement aux API web traditionnelles qui dépendent de pilotes de périphériques spécifiques, WebHID fournit une interface générique pour interagir avec une large gamme de dispositifs, tant que l'utilisateur accorde sa permission. Cela le rend idéal pour les périphériques qui n'ont pas de support natif dans le navigateur ou qui nécessitent une gestion d'entrée personnalisée.

Pourquoi utiliser WebHID ?

• Accès direct aux périphériques : Communiquez directement avec les périphériques HID sans dépendre des pilotes spécifiques au navigateur.
• Gestion d'entrée personnalisée : Implémentez un mappage et un traitement d'entrée personnalisés pour les appareils spécialisés.
• Large prise en charge des périphériques : Prenez en charge une plus grande gamme de périphériques, y compris les manettes de jeu, les instruments scientifiques et les contrôleurs industriels.
• Expérience utilisateur améliorée : Créez des expériences web plus immersives et interactives.

Comprendre les filtres de périphériques WebHID

Les filtres de périphériques sont essentiels pour demander l'accès à des périphériques HID spécifiques. Lorsque votre application web appelle navigator.hid.requestDevice(), le navigateur affiche un sélecteur de périphériques, permettant à l'utilisateur de sélectionner un appareil. Les filtres de périphériques vous permettent de réduire la liste des appareils présentés à l'utilisateur, facilitant ainsi la recherche du bon.

Un filtre de périphérique est un objet JavaScript qui spécifie des critères pour correspondre aux périphériques HID. Vous pouvez spécifier plusieurs filtres dans l'appel requestDevice(), et le navigateur n'affichera que les périphériques qui correspondent à au moins un des filtres.

Propriétés des filtres de périphériques

• vendorId (optionnel) : L'ID de Vendeur USB (Vendor ID) du périphérique. C'est un nombre de 16 bits qui identifie le fabricant du périphérique.
• productId (optionnel) : L'ID de Produit USB (Product ID) du périphérique. C'est un nombre de 16 bits qui identifie le modèle spécifique du périphérique.
• usagePage (optionnel) : La Page d'Utilisation HID (Usage Page) du périphérique. Elle identifie la catégorie du périphérique (par ex., Contrôles de Bureau Génériques, Contrôles de Jeu).
• usage (optionnel) : L'Utilisation HID (Usage) du périphérique. Elle identifie la fonction spécifique du périphérique au sein de la page d'utilisation (par ex., Joystick, Manette de jeu).

Vous pouvez utiliser une combinaison de ces propriétés pour créer des filtres très spécifiques. Par exemple, vous pourriez filtrer les périphériques avec un vendorId et un productId spécifiques pour cibler un modèle particulier de manette de jeu.

Exemples pratiques de filtres de périphériques

Voyons quelques exemples pratiques sur la manière d'utiliser les filtres de périphériques dans vos applications web.

Exemple 1 : Filtrer pour une manette de jeu spécifique

Supposons que vous souhaitiez cibler une manette de jeu spécifique avec un vendorId et un productId connus. Vous pouvez utiliser le filtre suivant :

            const filters = [
  {
    vendorId: 0x045e, // Microsoft
    productId: 0x028e, // Manette Xbox 360
  },
];

navigator.hid.requestDevice({ filters })
  .then((devices) => {
    // Gérer le(s) périphérique(s) sélectionné(s)
  })
  .catch((error) => {
    // Gérer les erreurs
  });

            

              
                Copy
              
            
          

Dans cet exemple, le filtre ne correspondra qu'aux périphériques ayant un vendorId de 0x045e (Microsoft) et un productId de 0x028e (Manette Xbox 360). Remplacez-les par l'ID de Vendeur et l'ID de Produit appropriés du périphérique que vous ciblez.

Exemple 2 : Filtrer pour n'importe quelle manette de jeu

Si vous voulez permettre à l'utilisateur de sélectionner n'importe quelle manette de jeu, vous pouvez utiliser un filtre qui spécifie la usagePage et l'usage pour les manettes de jeu :

            const filters = [
  {
    usagePage: 0x01, // Contrôles de Bureau Génériques
    usage: 0x05, // Manette de jeu
  },
];

navigator.hid.requestDevice({ filters })
  .then((devices) => {
    // Gérer le(s) périphérique(s) sélectionné(s)
  })
  .catch((error) => {
    // Gérer les erreurs
  });

            

              
                Copy
              
            
          

Ce filtre correspondra à tout périphérique HID qui s'identifie comme une manette de jeu en utilisant les codes d'utilisation HID standard.

Exemple 3 : Combiner les filtres

Vous pouvez combiner plusieurs filtres pour offrir plus de flexibilité. Par exemple, vous pourriez vouloir permettre à l'utilisateur de sélectionner soit un modèle de manette de jeu spécifique, soit n'importe quelle manette de jeu :

            const filters = [
  {
    vendorId: 0x045e, // Microsoft
    productId: 0x028e, // Manette Xbox 360
  },
  {
    usagePage: 0x01, // Contrôles de Bureau Génériques
    usage: 0x05, // Manette de jeu
  },
];

navigator.hid.requestDevice({ filters })
  .then((devices) => {
    // Gérer le(s) périphérique(s) sélectionné(s)
  })
  .catch((error) => {
    // Gérer les erreurs
  });

            

              
                Copy
              
            
          

Dans ce cas, le sélecteur de périphériques affichera à la fois la manette Xbox 360 spécifique (si elle est connectée) et tout autre appareil qui s'identifie comme une manette de jeu.

Exemple 4 : Filtrer pour un type de clavier spécifique sur un système

Certains claviers de niche nécessitent des codes HID spécifiques pour s'initialiser correctement. L'exemple suivant suppose que vous connaissez l'ID de vendeur, l'ID de produit, la page d'utilisation et l'utilisation pour le clavier. Vous pouvez généralement trouver ces informations dans la documentation du fabricant ou en utilisant des outils de listage de périphériques disponibles sur la plupart des systèmes d'exploitation.

            const filters = [
    {
        vendorId: 0x1234,  // Remplacez par votre ID de vendeur
        productId: 0x5678, // Remplacez par votre ID de produit
        usagePage: 0x07,   // Remplacez par votre page d'utilisation (ex: Clavier/Pavé numérique)
        usage: 0x01      // Remplacez par votre utilisation (ex: Clavier)
    }
];

navigator.hid.requestDevice({ filters })
  .then((devices) => {
    // Gérer le(s) périphérique(s) sélectionné(s)
  })
  .catch((error) => {
    // Gérer les erreurs
  });

            

              
                Copy
              
            
          

Obtenir des informations sur le périphérique

Une fois que l'utilisateur a sélectionné un périphérique, vous pouvez accéder à ses informations en utilisant l'objet HIDDevice.

Propriétés de HIDDevice

• vendorId : L'ID de Vendeur USB du périphérique.
• productId : L'ID de Produit USB du périphérique.
• productName : Le nom du périphérique.
• collections : Un tableau d'objets HIDCollection représentant les descripteurs de rapport HID du périphérique.

Vous pouvez utiliser ces informations pour identifier le périphérique et configurer votre application en conséquence.

Gestion des rapports HID

Après avoir obtenu un HIDDevice, vous devez l'ouvrir et commencer à écouter les rapports HID. Les rapports HID sont les données brutes envoyées par le périphérique à votre application.

Ouverture du périphérique

            device.open()
  .then(() => {
    console.log('Périphérique ouvert');

    // Commencer à écouter les rapports d'entrée
    device.addEventListener('inputreport', (event) => {
      const { data, reportId } = event;
      // Traiter le rapport d'entrée
      console.log(`Rapport d'entrée reçu avec l'ID ${reportId}:`, data);
    });
  })
  .catch((error) => {
    console.error('Échec de l'ouverture du périphérique :', error);
  });

            

              
                Copy
              
            
          

Traitement des rapports d'entrée

Les rapports d'entrée sont reçus sous forme d'objets DataView. La structure des données dépend du descripteur de rapport HID du périphérique. Vous devrez consulter la documentation du périphérique pour comprendre comment interpréter les données.

Voici un exemple simplifié de la manière de traiter un rapport d'entrée :

            device.addEventListener('inputreport', (event) => {
  const { data, reportId } = event;

  // En supposant que le premier octet du rapport représente l'état du bouton
  const buttonState = data.getUint8(0);

  // Traiter l'état du bouton
  if (buttonState & 0x01) {
    console.log('Bouton 1 pressé');
  }
  if (buttonState & 0x02) {
    console.log('Bouton 2 pressé');
  }
});

            

              
                Copy
              
            
          

Ceci est un exemple très basique. Les périphériques HID du monde réel ont souvent des structures de rapport plus complexes. La rétro-ingénierie du rapport HID peut être un processus complexe ; cependant, des outils sont disponibles pour aider au processus d'analyse.

Gestion des erreurs

Il est important de gérer les erreurs avec élégance lorsque l'on travaille avec WebHID. Voici quelques erreurs courantes que vous pourriez rencontrer :

• SecurityError : L'utilisateur a refusé la permission d'accéder aux périphériques HID.
• NotFoundError : Aucun périphérique correspondant n'a été trouvé.
• InvalidStateError : Le périphérique est déjà ouvert.
• Autres erreurs : Erreurs USB, déconnexions inattendues de périphériques.

Enveloppez toujours votre code WebHID dans des blocs try...catch et fournissez des messages d'erreur informatifs à l'utilisateur.

Meilleures pratiques pour le développement WebHID

• Utilisez des filtres de périphériques : Utilisez toujours des filtres de périphériques pour réduire la liste des appareils présentés à l'utilisateur.
• Fournissez des instructions claires : Guidez les utilisateurs sur la manière de connecter et d'autoriser le périphérique. Si le périphérique n'apparaît pas, expliquez à l'utilisateur où trouver les ID de Vendeur et de Produit pour les appareils courants.
• Gérez les erreurs avec élégance : Mettez en œuvre une gestion robuste des erreurs pour offrir une expérience utilisateur fluide.
• Consultez la documentation du périphérique : Référez-vous à la documentation du périphérique pour comprendre son descripteur de rapport HID.
• Testez sur plusieurs plateformes : Testez votre application sur différents navigateurs et systèmes d'exploitation pour garantir la compatibilité.
• Tenez compte de la sécurité : Soyez conscient des implications de sécurité lorsque vous travaillez avec les entrées utilisateur. Assainissez les données et évitez d'exécuter du code non fiable.
• Proposez des options de repli : Si WebHID n'est pas pris en charge ou si l'utilisateur refuse la permission, proposez des méthodes d'entrée alternatives.

Techniques avancées

Rapports de fonctionnalités (Feature Reports)

En plus des rapports d'entrée, les périphériques HID peuvent également envoyer et recevoir des rapports de fonctionnalités. Les rapports de fonctionnalités sont utilisés pour configurer le périphérique ou récupérer son état.

Pour envoyer un rapport de fonctionnalité, utilisez la méthode device.sendFeatureReport().

            const reportId = 0x01;
const data = new Uint8Array([0x01, 0x02, 0x03]); // Données d'exemple

device.sendFeatureReport(reportId, data)
  .then(() => {
    console.log('Rapport de fonctionnalité envoyé avec succès');
  })
  .catch((error) => {
    console.error('Échec de l'envoi du rapport de fonctionnalité :', error);
  });

            

              
                Copy
              
            
          

Pour recevoir un rapport de fonctionnalité, utilisez la méthode device.getFeatureReport().

            const reportId = 0x01;

device.getFeatureReport(reportId)
  .then((data) => {
    console.log('Rapport de fonctionnalité reçu :', data);
  })
  .catch((error) => {
    console.error('Échec de la réception du rapport de fonctionnalité :', error);
  });

            

              
                Copy
              
            
          

Rapports de sortie (Output Reports)

WebHID prend également en charge les rapports de sortie, qui vous permettent d'envoyer des données *au* périphérique. Par exemple, vous pourriez utiliser des rapports de sortie pour contrôler des LED ou d'autres actionneurs sur le périphérique.

Pour envoyer un rapport de sortie, utilisez la méthode device.sendReport().

            const reportId = 0x01;
const data = new Uint8Array([0x01, 0x02, 0x03]); // Données d'exemple

device.sendReport(reportId, data)
  .then(() => {
    console.log('Rapport de sortie envoyé avec succès');
  })
  .catch((error) => {
    console.error('Échec de l'envoi du rapport de sortie :', error);
  });

            

              
                Copy
              
            
          

Considérations de sécurité

L'accès à WebHID nécessite la permission de l'utilisateur, ce qui aide à atténuer certains risques de sécurité. Cependant, il est toujours important d'être conscient des vulnérabilités potentielles.

• Assainissement des données : Assainissez toujours les données reçues des périphériques HID pour prévenir l'injection de code ou d'autres attaques.
• Restrictions d'origine : WebHID est soumis à la politique de même origine (same-origin policy), qui empêche l'accès inter-origines aux périphériques HID.
• Sensibilisation de l'utilisateur : Éduquez les utilisateurs sur les risques d'accorder l'accès aux périphériques HID et encouragez-les à n'accorder la permission qu'à des sites web de confiance.

Perspectives mondiales et exemples

L'API WebHID a des implications mondiales, permettant aux développeurs de créer des applications web qui prennent en charge une large gamme de périphériques de différents fabricants et régions. Considérez ces exemples :

• Jeux vidéo : Prise en charge des manettes de jeu de divers fabricants à travers différents pays (par ex., les manettes Sony PlayStation, les manettes Microsoft Xbox, la manette Nintendo Switch Pro, et des marques moins connues d'Asie et d'Europe).
• Accessibilité : Création de dispositifs d'entrée personnalisés pour les utilisateurs handicapés, en tenant compte des différentes normes et préférences régionales en matière d'accessibilité. Par exemple, des claviers spécialisés ou des interfaces à contacteur conçus pour des besoins spécifiques et disponibles dans différentes dispositions.
• Automatisation industrielle : Interface avec des contrôleurs et capteurs industriels utilisés dans les usines du monde entier, prenant en charge différents protocoles de communication et formats de données.
• Recherche scientifique : Connexion à des instruments scientifiques utilisés dans des laboratoires de recherche à l'échelle mondiale, permettant aux chercheurs de collecter et d'analyser des données directement dans des applications web. Imaginez contrôler un équipement de laboratoire dans une université à Tokyo depuis l'ordinateur portable d'un chercheur à Londres.
• Éducation : Prise en charge de robots éducatifs et d'appareils interactifs utilisés dans les salles de classe du monde entier, offrant aux étudiants des expériences d'apprentissage pratiques. Cela pourrait inclure des robots de codage fabriqués en Chine utilisés dans une salle de classe au Brésil.

WebHID vs autres API Web

Il est utile de comparer WebHID à d'autres API web liées à l'interaction avec les périphériques :

• API Gamepad : L'API Gamepad fournit une interface de plus haut niveau spécifiquement pour les manettes de jeu. WebHID offre plus de flexibilité et de contrôle mais nécessite une gestion manuelle plus importante des données du périphérique. L'API Gamepad est bien adaptée aux manettes de jeu courantes, tandis que WebHID peut prendre en charge des dispositifs d'entrée plus exotiques ou spécialisés.
• API WebUSB : WebUSB permet aux applications web de communiquer directement avec les périphériques USB. WebHID est spécifiquement conçu pour les Périphériques d'Interface Humaine, tandis que WebUSB peut être utilisé pour une plus large gamme de périphériques USB. WebUSB pourrait être utilisé pour un instrument scientifique spécialisé connecté via USB, alors que WebHID serait utilisé pour un clavier ou une souris personnalisée.
• API Web Serial : Web Serial permet la communication via des ports série. Ceci est utile pour interagir avec des systèmes embarqués et d'autres appareils qui communiquent via des connexions série. Un microcontrôleur envoyant des données via une connexion série pourrait utiliser Web Serial, tandis qu'un joystick personnalisé utiliserait WebHID.

L'avenir de WebHID

L'API WebHID est en constante évolution, avec des efforts continus pour améliorer sa sécurité, ses performances et sa facilité d'utilisation. À mesure que de plus en plus d'appareils adoptent la norme HID, WebHID deviendra un outil de plus en plus important pour les développeurs web. Attendez-vous à voir des fonctionnalités plus avancées et un meilleur support des navigateurs à l'avenir.

Conclusion

WebHID est une API puissante qui ouvre un large éventail de possibilités pour les applications web. En comprenant les filtres de périphériques et la manière de gérer les rapports HID, vous pouvez créer des expériences web engageantes et interactives qui exploitent tout le potentiel des Périphériques d'Interface Humaine. Que vous construisiez un jeu, un outil d'accessibilité ou un système de contrôle industriel, WebHID peut vous aider à connecter votre application web au monde physique. N'oubliez pas de prioriser l'expérience utilisateur, la sécurité et la compatibilité multiplateforme pour créer des applications WebHID réussies et globalement accessibles.